Summary

This PR delivers a full structural overhaul of the omop-alchemy maintenance CLI, motivated by accumulated complexity, duplicated boilerplate across every command, raw SQL scattered through CLI files, and documentation that was insufficient to understand how commands should be used.

Fixes #12

Part 1: CLI cleanup

Backend abstraction layer

A new omop_alchemy/backends/ package introduces a Backend ABC with PostgresBackend and SQLiteBackend implementations. All dialect-specific SQL (FK trigger toggling, ANALYZE/TRUNCATE/sequence management, CLUSTER, full-text sidecar management, backup/restore command assembly) is extracted from the CLI files and centralised in the backend implementations. CLI files are now orchestration and rendering only.

• backend_support.py deleted and replaced by backend_supports / require_backend_support / BackendNotSupportedError on the Backend base class
• cdm/handlers/fulltext/ deleted; full-text logic absorbed into backends/fulltext.py and PostgresBackend

@omop_command decorator

An @omop_command decorator in _cli_utils.py eliminates three repeated patterns from all 18 CLI command functions: connection parameter declarations (--dotenv, --engine-schema, --db-schema), setup_cli_cmd boilerplate, and try/except handle_error wrappers. Command bodies now only see a resolved conn object and a ready engine.

cli_schema.py decomposed

The 1,500-line monolithic file was split into five single-responsibility domain modules (cli_schema_info.py, cli_schema_doctor.py, cli_schema_reconcile.py, cli_schema_tables.py, cli_schema_summary.py). The original file is retained as a thin re-export shim so all existing callers continue to work unchanged.

Documentation

• Module-level docstrings added to all 14 CLI source files
• Docstring style standardised (no semicolons as clause joiners)
• New docs/cli/index.md: CLI architecture overview covering the @omop_command decorator, connection resolution, and the conn object
• New docs/cli/reference.md: full command reference with parameter tables for all 25 commands
• MkDocs nav corrected: all orphaned model, API, and advanced pages added; dead reference removed

Part 2: Accelerated ingestion of vocabularies

** To be done**

Part 3: OA Configurator integration

PENDING

Integration with the OA Configurator will absorb the engine-creation and configuration machinery (db.py, config.py, logger_config.py) from this package into the shared configuration tool. The backends/ layer is configuration-agnostic by design and will slot in unchanged when this work is complete.

This section will be updated when the integration is ready.